% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/convert_units.R
\name{convert_units}
\alias{convert_units}
\title{Convert units of distance or area}
\usage{
convert_units(x, from = "km", towhat = "mi")
}
\arguments{
\item{x}{A number or vector of numbers to be converted.}

\item{from}{A string specifying original units of input parameter. Default is 'km' which is kilometers.
Note all must be in the same units.
Units can be specified as any of the following:
c(
'millimeter', 'millimeters', 'centimeter', 'centimeters', 'meter', 'meters', 'kilometer', 'kilometers',
"mm", "cm", "m", "km",
"sqmm", "sqcm", "sqm", "sqkm",
"mm2", "cm2", "m2", "km2",
'inch', 'inches', 'foot', 'feet', 'yard', 'yards', 'mile', 'miles',
"in", "ft", "yd", "mi",
"sqin", "sqft", "sqyd", "sqmi",
"in2", 'ft2', 'yd2', 'mi2'
)
Note that m2 is for square meters not square miles.}

\item{towhat}{A string specifying new units to convert to. Default is 'mi' which is miles.}
}
\value{
Returns a number or vector of numbers then length of the input x,
with each element corresponding to an input element converted to new units.
}
\description{
\code{convert_units} converts distance or area from specified units to other specified units.
}
\details{
This function takes a number, or vector of numbers, representing distance/length or area
in one type of specified units, such as miles, and returns the corresponding number(s)
converted to some other units, such as kilometers. Units can be specified in various ways.
All inputs must be in the same units. All outputs must be in a single set of units as well.

NOTE: For some purposes, Census Bureau does this:

"The ANSI standard for converting square kilometers into square miles was used
( 1 square mile = 2.58998811 square kilometers)."
see \url{https://www.census.gov/geo/reference/state-area.html}
but the conversions in this function use 2.5899881034 not 2.58998811 sqkm/sqmi.
The difference is only 6.6 per billion (roughly 1 in 152 million), which is less than one tenth of a square kilometer out the entire USA.
}
\examples{
convert_units(1, 'mi', 'km')
convert_units(c(1e6, 1), 'sqm', 'sqkm')

}
